Repository navigation
spec(FIX-1906): coding runs for mapped projects work in worktrees of your checkout - #3177
Conversation
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second-look + architecture review (direction check, not a rewrite)Read SPEC, DECISIONS, BUSINESS-RULES, PLAN and the POC against 1. Worktrees and branches in the operator's checkout have no lifecycle (worth a rule)D3 makes every settled run's worktree and branch permanent, and BR-13 to BR-15 say what happens when a person removes one. Nothing says who removes them or what accumulates. Every mapped run adds a 2. D3's rejected alternative is the weaker oneD3 rejects "detach HEAD on settle". The more natural alternative is not rejected anywhere: remove the worktree on settle and keep the branch. BR-14 already proves the host re-adds a worktree on an existing branch, and a held-work store exists for uncommitted files. That would leave the branch free to 3. D1's double-naming has an unguarded mismatchThe checkout is named in 4. The epic's retained spec now contradicts this oneEpic D3 and ER-9 say the workspace host gains the mapping. D1 puts it in 5. Weight versus what is askedThe PR says there is no open question for the owner, yet it ships 12 files / about 1,100 lines, with four SVG figures for three decisions it calls engineering calls. D2 and D3 read as "decided, not asked" items. Not a blocker, but if the figures are the cost-driver for reviewers, D2 and D3 could drop theirs and keep the one-line "it comes down to" sentence. 6. Implementation notes (no spec change)
No changes needed to the D1 fence or the S1/S2 split. Generated by Claude Code |
There was a problem hiding this comment.
Simplify review (FIX-1906 spec)
Verdict: Approve direction. The core design is the right trade for BP-031 and continuation semantics; complexity is mostly in surface area (docs, epic alignment, operator config), not in the worktree model itself.
What looks like the right approach
- D1 (mapping on
projectWorkspace(), full address) is the simpler correct design vs a host option keyed on bareprojectId. The private-twin case is real (projectAddressSchema), and pushing visibility into the source matches how answers are already formed. - D2 (agent install + shared pnpm store) avoids the silent “tests import the checkout” failure mode from linked
node_modules. The kill-line POC (poc/kill-line/) is appropriate retained evidence for a spec that gates the epic. - D3 (branch stays checked out) follows from existing harness-manager continuation goals; detaching would be a larger behavioral change.
- Implementation plan (S1–S2) reuses existing shapes: remote runs already use
checkout/+project/; local mapped runs generalize that instead of inventing a parallel layout. No need forsimple-git— extendworktree.ts/exec.tsand existinglocal-host-*tests.
Where the approach went further than necessary (optional trims)
- Epic text vs D1 without an epic amendment — FIX-1903 D3/ER-9 still read as “the workspace host gains that mapping.” EVOLUTION records coordinator acceptance as a “stricter reading.” That works procedurally (ER-17), but it leaves two canonical stories. Simpler: a small follow-up epic amend (one paragraph in D3 + ER-9: mapping lives on
projectWorkspace, host allowlist unchanged) so implementers and FIX-1904’s profile author aren’t reconciling cross-links. - Operator config names the checkout twice (
localRepositories+checkouts[].checkout) — acknowledged in D1. Simpler (if you want less foot-gun): document that FIX-1904’s host wiring should derive the allowlist from uniquecheckouts[].checkoutvalues, or validate equality at boot and refuse on mismatch (beyond BR-5’s path-not-listed case). - Spec volume — 20 BRs, three decision SVGs, fence mermaid in both SPEC and BUSINESS-RULES, plus DECISIONS “Settled” repeating the POC table. The contract could live in ~12 BRs + PLAN guardrails; figures could be mermaid-only unless you need SVG for the spec site.
- Goal check signal — leg a bundles in-checkout, offline install, build, branch, and note-saved. The kill line is already proved in the POC; the goal could assert mapping + one install/build smoke and leave note-saved to workforce/workspace unit tests (still required by BR-11). Optional, not blocking.
- POC F3 (36 concurrent worktrees) is stronger than V3 needs (two projects × 10). Fine as spike evidence; don’t feel obliged to imply CI must reproduce 36-way stress.
Alternatives considered (and why I’d still stay on this PR)
| Alternative | Why it’s tempting | Why this spec still wins |
|---|---|---|
| Host-side mapping once source carries full address | One config surface, matches epic wording | Needs a trusted address on every RunSource answer first; workforce-only option is smaller now |
| Fold FIX-1906 into FIX-1904 | One PR for “dev Lab works” | Epic D1 explicitly keeps kill-line + host capability separate; risk isolation is real |
Host runs pnpm install after provision |
Agents might skip install | D2’s flip is documented; 6s on warm store is cheap vs wrong imports |
Require only checkouts (drop duplicate path) |
Less config | localRepositories is the existing security allowlist; dropping it is a wider API change |
Merge hygiene (not a design block)
The GitHub diff against 982524… shows deleting FIX-1185 because this branch forks before #3166 landed on main. A rebase onto current main before merge should make the PR diff “add FIX-1906 only.” Worth doing so reviewers don’t think FIX-1185 is being reverted.
Performance / ops (spec-level)
Cold pnpm store and cold turbo cache are the real costs; the spec documents them. Turbo sharing across worktrees is a good finding — worth keeping the “re-run POC after pnpm/turbo bump” line in PLAN.
Happy to see implementation follow existing test harnesses (local-host-repo.spec.ts, project-workspace-task.test.ts, goals/devforce-lab/it-codes-in-the-projects-repository) rather than new frameworks.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5daab6d084
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
FIX-1906 round 1 (#3177, 0c42dfd) keys `checkouts[].projects` on `{ orgId, id, tenantId? }` for shared projects only. The profile's entries now name the Lab's `LAB_ORG_ID` (teams/devteam/host.mts), and `localRepositories` is derived from the `checkouts` paths. BR-14 names an org-less or other-org session as a miss, refused by name under D3. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JdyQCD5rESK6t4xABFzRZk
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@claude is this design config time only or does it work with data driven cases where we can change a project's settings through the interface? |
|
from: fsd-claude Which projects can use your checkout is set in config only, read when the server starts. The rest of a project stays data-driven.
If you want to grant it from the interface later, the safe version is an operator-only setting stored on the host's side, not on the project row. Only the server's operator could change it, and it would take effect without a restart. That is a small follow-up on top of this spec and changes nothing in it. The dev profile doesn't need it, because its two projects are fixed. I'd leave it out of this epic and file it if you want it. Generated by Claude Code |


Requested by Jake · project thread
Retained spec for FIX-1906, under epic FIX-1903. Start at
specs/issues/FIX-1906/SPEC.md.Before: a project's coding run gets a branch in a hidden clone that the host made. A local repository can't keep the project's files beside the worktree, and nothing ties a project to a person's checkout.
After: the operator's config names a checkout and the shared projects it serves, each identified by its organization and id. A run on one of those projects gets a fresh worktree of that checkout. Its branch lives there, and the project's files sit in
project/beside the worktree. Some projects never get a worktree of the checkout: one the config doesn't name, a project with the same id in another organization, and any private project.The kill line is cleared. A fresh worktree of this monorepo installs offline from the machine's shared pnpm store in 6 s, and builds every package in 86 s. That build cost is paid once per change, because turbo's cache is shared across worktrees. Its tests pass. The proof can be re-run from
poc/kill-line/check.sh.How: the mapping is an option of workforce's
projectWorkspace()(D1). It is matched against the stored row and the run's server-set organization. The host can't hold the mapping, because it only sees a bare id. The epic coordinator accepted this as a stricter reading of ER-13. Workspace's local-repository mode learns to keep files beside the checkout. A settled run's branch stays checked out, and continuing the run is proved on the mapped path (D3). Two projects on one checkout are tested with a control that must fail.What's asked of you
The direction only. D1 to D3 are engineering calls, and there is no open question for the owner. Merging this PR is the approval, and implementation starts when it merges.
🤖 Generated with Claude Code
https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo